QuickTime 3 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Specifying the Data Source

Graphics importer components use QuickTime data handler components to obtain their data. Applications, however, will use the graphics importer component functions described in this section, rather than directly calling a data handler. These functions allow the data source to be a file, a handle, or a QuickTime data reference.

You do not need to call the functions in this section if you use one of the GetGraphicsImporter functions. The GetGraphicsImporter functions automatically set the graphics importer component's data source. You only need to use these functions if you open the graphics importer component directly.

GraphicsImportSetDataFile

Specifies the file that the graphics data resides in.

extern pascal ComponentResult GraphicsImportSetDataFile (
            GraphicsImportComponent ci,
            const FSSpec *theFile);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

theFile     A pointer to the file specification containing the graphics data.

DISCUSSION

The file will be opened for read access.

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportGetDataFile

Returns the file that the graphics data resides in.

extern pascal ComponentResult GraphicsImportGetDataFile (
            GraphicsImportComponent ci,
            FSSpec *theFile);

ci      Specifies the component instance that identifies your connection to the graphics importer component.

theFile      A pointer in which to return the file containing the graphics data.

DISCUSSION

You use this function to get the file system specification record for the file that the graphics data resides in. If the data source is not a file, the function returns paramErr .

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportSetDataHandle

Specifies the handle that the graphics data resides in.

extern pascal ComponentResult GraphicsImportSetDataHandle (
            GraphicsImportComponent ci,
            Handle h);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

h     Specifies a handle containing graphics data.

DISCUSSION

The graphics importer component doesn't make a copy of this data. Therefore you must not dispose this handle until the graphics importer has been closed.

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available.

GraphicsImportGetDataHandle

Returns the handle that the graphics data resides in.

extern pascal ComponentResult GraphicsImportGetDataHandle (
            GraphicsImportComponent ci,
            Handle *h);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

h      A pointer to a handle to return a handle containing the graphics data.

DISCUSSION

You use this function to get the handle that the graphics data resides in. If the data source is not a handle, the function returns paramErr.

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportSetDataReference

Specifies the data reference that the graphics data resides in.

extern pascal ComponentResult GraphicsImportSetDataReference (
            GraphicsImportComponent ci,
            Handle dataRef,
            OSType dataReType);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

dataRef      A pointer to a handle to return a QuickTime data reference.

dataReType      A pointer to the data reference type.

DISCUSSION

Applications typically do not use this function. The GraphicsImportSetDataFile and GraphicsImportSetDataHandle functions both call this function, with the appropriate data reference and data reference type.

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportGetDataReference

Returns the data reference that the graphics data resides in.

extern pascal ComponentResult GraphicsImportGetDataReference (
            GraphicsImportComponent ci,
            Handle *dataRef,
            OSType *dataReType);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

dataRef      A pointer to the handle to return a QuickTime data reference.

dataReType      A pointer to the data reference type.

DISCUSSION

You use this function to get the data reference that the graphics data resides in. Both the dataRef and dataReType parameters may be set to nil if the corresponding information is not desired. The GraphicsImportGetDataHandle and GraphicsImportGetDataFile functions call GraphicsImporGetDataReference and then manipulate the result accordingly. The caller should disposed of the returned dataRef .

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportSetDataReferenceOffsetAndLimit

Specifies the data reference starting offset and data size limit.

extern pascal ComponentResult GraphicsImportSetDataReferenceOffsetAndLimit (
            GraphicsImportComponent ci,
            unsigned long offset,
            unsigned long limit);

ci     Specifies the component instance that identifies your connection to the graphics importer component.

offset     The byte offset of the image data from the beginning of the data reference.

limit     The data limit. This value is the maximum offset into the data reference that data may be read from.

DISCUSSION

A data reference typically refers to an entire file. However, there are times when the data being referenced is a part of a larger file. In these cases, it is necessary to indicate where the data begins in the data reference and where it ends. This function lets you specify the starting offset and ending offset. All requests to read data are then relative to the specified offset, and are pinned to the data size, so the grapics importer component cannot accidentally read off the end (or beginning) of the segment.

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available

GraphicsImportGetDataReferenceOffsetAndLimit

Returns the data reference starting offset and data size limit.

extern pascal ComponentResult GraphicsImportGetDataReferenceOffsetAndLimit (
            GraphicsImportComponent ci,
            unsigned long *offset,
            unsigned long *limit);

ci      Specifies the component instance that identifies your connection to the graphics importer component.

offset      A pointer to a value describing the byte offset of the image data from the beginning of the data reference.

limit      A pointer to a value describing the data size limit.

DISCUSSION

This function returns the values set by the GraphicsImportSetDataReferenceOffsetAndLimit function. By default, offset is 0 and limit is MaxInt (2^32 - 1).

RESULT CODES
noErr
0 No error
paramErr
-50 Invalid parameter specified
memFullErr
-108 Not enough memory available
© 1998 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |